{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://raw.githubusercontent.com/Qiskit/qiskit-tutorials/master/images/qiskit-heading.png\" alt=\"Note: In order for images to show up in this jupyter notebook you need to select File => Trusted Notebook\" width=\"500 px\\\" align=\"left\">"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Quantum Volume Overview\n",
    "\n",
    "### Contributors\n",
    "\n",
    "Shelly Garion$^{1}$ and David McKay$^{2}$\n",
    "\n",
    "1. IBM Research Haifa, Haifa University Campus, Mount Carmel Haifa, Israel\n",
    "2. IBM T.J. Watson Research Center, Yorktown Heights, NY, USA"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "**Quantum Volume (QV)** is a single-number metric that can be measured using a concrete\n",
    "protocol on near-term quantum computers of modest size. The QV method quantifies\n",
    "the largest random circuit of equal width and depth that the computer successfully implements.\n",
    "Quantum computing systems with high-fidelity operations, high connectivity, large calibrated gate\n",
    "sets, and circuit rewriting toolchains are expected to have higher quantum volumes. \n",
    "\n",
    "\n",
    "### References\n",
    "\n",
    "[1] Andrew W. Cross, Lev S. Bishop, Sarah Sheldon, Paul D. Nation, and Jay M. Gambetta, *Validating quantum computers using randomized model circuits*, https://arxiv.org/pdf/1811.12926\n",
    "\n",
    "\n",
    "\n",
    "## The Quantum Volume Protocol\n",
    "\n",
    "A QV protocol (see [1]) consists of the following steps:\n",
    "\n",
    "(We should first import the relevant qiskit classes for the demonstration)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "#Import general libraries (needed for functions)\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "#Import Qiskit classes classes\n",
    "import qiskit\n",
    "from qiskit.providers.aer.noise import NoiseModel\n",
    "from qiskit.providers.aer.noise.errors.standard_errors import depolarizing_error, thermal_relaxation_error\n",
    "\n",
    "#Import the qv function.\n",
    "import qiskit.ignis.verification.quantum_volume as qv"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1: Generate QV sequences\n",
    "\n",
    "It is well-known that quantum algorithms can be expressed as polynomial-sized quantum circuits built from two-qubit unitary gates. Therefore, a model circuit consists of $d$ layers of random permutations of the qubit labels, followed by random two-qubit gates (from $SU(4)$). When the circuit width $m$ is odd, one of the qubits is idle in each layer.\n",
    "\n",
    "More precisely, a **QV circuit** with **depth $d$** and **width $m$**, is a sequence $U = U^{(d)}...U^{(2)}U^{(1)}$ of $d$ layers:\n",
    "$$ U^{(t)} = U^{(t)}_{\\pi_t(m'-1),\\pi_t(m)} \\otimes ... \\otimes U^{(t)}_{\\pi_t(1),\\pi_t(2)} $$\n",
    "each labeled by times $t = 1 ... d$ and acting on $m' = 2 \\lfloor n/2 \\rfloor$ qubits. \n",
    "Each layer is specified by choosing a uniformly random permutation $\\pi_t \\in S_m$ of the $m$ qubit indices\n",
    "and sampling each $U^{(t)}_{a,b}$, acting on qubits $a$ and $b$, from the Haar measure on $SU(4)$.\n",
    "\n",
    "In the following example we have 6 qubits Q0,Q1,Q3,Q5,Q7,Q10. We are going to look at subsets up to the full set\n",
    "(each volume circuit will be depth equal to the number of qubits in the subset)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "# qubit_lists: list of list of qubit subsets to generate QV circuits\n",
    "qubit_lists = [[0,1,3],[0,1,3,5],[0,1,3,5,7],[0,1,3,5,7,10]]\n",
    "# ntrials: Number of random circuits to create for each subset\n",
    "ntrials = 50"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We generate the quantum volume sequences. We start with a small example (so it doesn't take too long to run)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "qv_circs, qv_circs_nomeas = qv.qv_circuits(qubit_lists, ntrials)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As an example, we print the circuit corresponding to the first QV sequence. Note that the ideal circuits are run on the first n qubits (where n is the number of qubits in the subset)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "#pass the first trial of the nomeas through the transpiler to illustrate the circuit\n",
    "qv_circs_nomeas[0] = qiskit.compiler.transpile(qv_circs_nomeas[0], basis_gates=['u1','u2','u3','cx'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "         ┌──────────────────────────────┐                                  »\n",
      "qr_0: |0>┤ U3(0.87222,-3.6056,-0.99855) ├──────────────────────────────────»\n",
      "         └┬────────────────────────────┬┘     ┌───────────────────────────┐»\n",
      "qr_1: |0>─┤ U3(0.52509,-1.8514,0.3785) ├───■──┤ U3(0.63498,1.5708,4.7124) ├»\n",
      "         ┌┴────────────────────────────┤ ┌─┴─┐└──┬─────────────────────┬──┘»\n",
      "qr_2: |0>┤ U3(1.9895,0.0074621,5.0423) ├─┤ X ├───┤ U3(1.5708,0,-5.713) ├───»\n",
      "         └─────────────────────────────┘ └───┘   └─────────────────────┘   »\n",
      " cr_0: 0 ══════════════════════════════════════════════════════════════════»\n",
      "                                                                           »\n",
      " cr_1: 0 ══════════════════════════════════════════════════════════════════»\n",
      "                                                                           »\n",
      " cr_2: 0 ══════════════════════════════════════════════════════════════════»\n",
      "                                                                           »\n",
      "«                                                  »\n",
      "«qr_0: ────────────────────────────────────────────»\n",
      "«           ┌────────────────────────────────┐     »\n",
      "«qr_1: ──■──┤ U3(0.33219,-1.7764e-15,4.7124) ├──■──»\n",
      "«      ┌─┴─┐└─┬────────────────────────────┬─┘┌─┴─┐»\n",
      "«qr_2: ┤ X ├──┤ U3(1.5708,-3.1416,-1.5708) ├──┤ X ├»\n",
      "«      └───┘  └────────────────────────────┘  └───┘»\n",
      "«cr_0: ════════════════════════════════════════════»\n",
      "«                                                  »\n",
      "«cr_1: ════════════════════════════════════════════»\n",
      "«                                                  »\n",
      "«cr_2: ════════════════════════════════════════════»\n",
      "«                                                  »\n",
      "«                                                                       »\n",
      "«qr_0: ─────────────────────────────────────────────────────────────────»\n",
      "«      ┌────────────────────────────┐┌────────────────────────────┐     »\n",
      "«qr_1: ┤ U3(1.9521,5.8535,0.045854) ├┤ U3(1.1882,3.6057,-0.89911) ├──■──»\n",
      "«      ├────────────────────────────┤├───────────────────────────┬┘┌─┴─┐»\n",
      "«qr_2: ┤ U3(0.51454,2.5314,-2.1542) ├┤ U3(0.86532,0.8319,2.0513) ├─┤ X ├»\n",
      "«      └────────────────────────────┘└───────────────────────────┘ └───┘»\n",
      "«cr_0: ═════════════════════════════════════════════════════════════════»\n",
      "«                                                                       »\n",
      "«cr_1: ═════════════════════════════════════════════════════════════════»\n",
      "«                                                                       »\n",
      "«cr_2: ═════════════════════════════════════════════════════════════════»\n",
      "«                                                                       »\n",
      "«                                                                           »\n",
      "«qr_0: ─────────────────────────────────────────────────────────────────────»\n",
      "«        ┌───────────────────────────┐       ┌─────────────────────────────┐»\n",
      "«qr_1: ──┤ U3(0.94961,1.5708,4.7124) ├────■──┤ U3(0.0076131,3.1416,1.5708) ├»\n",
      "«      ┌─┴───────────────────────────┴─┐┌─┴─┐└┬────────────────────────────┤»\n",
      "«qr_2: ┤ U3(1.5708,-4.4409e-16,-5.938) ├┤ X ├─┤ U3(1.5708,-3.1416,-1.5708) ├»\n",
      "«      └───────────────────────────────┘└───┘ └────────────────────────────┘»\n",
      "«cr_0: ═════════════════════════════════════════════════════════════════════»\n",
      "«                                                                           »\n",
      "«cr_1: ═════════════════════════════════════════════════════════════════════»\n",
      "«                                                                           »\n",
      "«cr_2: ═════════════════════════════════════════════════════════════════════»\n",
      "«                                                                           »\n",
      "«                                                                            »\n",
      "«qr_0: ───────────────────────────────────────────────────────────────────■──»\n",
      "«            ┌────────────────────────────┐┌───────────────────────────┐┌─┴─┐»\n",
      "«qr_1: ──■───┤ U3(1.0471,-1.5044,-2.6216) ├┤ U3(0.83828,-3.7118,-2.27) ├┤ X ├»\n",
      "«      ┌─┴─┐┌┴────────────────────────────┤└───────────────────────────┘└───┘»\n",
      "«qr_2: ┤ X ├┤ U3(0.68382,-3.5321,-1.3577) ├──────────────────────────────────»\n",
      "«      └───┘└─────────────────────────────┘                                  »\n",
      "«cr_0: ══════════════════════════════════════════════════════════════════════»\n",
      "«                                                                            »\n",
      "«cr_1: ══════════════════════════════════════════════════════════════════════»\n",
      "«                                                                            »\n",
      "«cr_2: ══════════════════════════════════════════════════════════════════════»\n",
      "«                                                                            »\n",
      "«        ┌───────────────────────────┐        »\n",
      "«qr_0: ──┤ U3(0.90513,1.5708,4.7124) ├─────■──»\n",
      "«      ┌─┴───────────────────────────┴──┐┌─┴─┐»\n",
      "«qr_1: ┤ U3(1.5708,-4.4409e-16,-6.2526) ├┤ X ├»\n",
      "«      └────────────────────────────────┘└───┘»\n",
      "«qr_2: ───────────────────────────────────────»\n",
      "«                                             »\n",
      "«cr_0: ═══════════════════════════════════════»\n",
      "«                                             »\n",
      "«cr_1: ═══════════════════════════════════════»\n",
      "«                                             »\n",
      "«cr_2: ═══════════════════════════════════════»\n",
      "«                                             »\n",
      "«      ┌────────────────────────────────┐     ┌─────────────────────────────┐\n",
      "«qr_0: ┤ U3(0.25732,-2.2204e-15,4.7124) ├──■──┤ U3(1.7629,3.2103,-0.053929) ├\n",
      "«      └─┬────────────────────────────┬─┘┌─┴─┐└┬───────────────────────────┬┘\n",
      "«qr_1: ──┤ U3(1.5708,-3.1416,-1.5708) ├──┤ X ├─┤ U3(2.3943,0.23818,0.7056) ├─\n",
      "«        └────────────────────────────┘  └───┘ └───────────────────────────┘ \n",
      "«qr_2: ──────────────────────────────────────────────────────────────────────\n",
      "«                                                                            \n",
      "«cr_0: ══════════════════════════════════════════════════════════════════════\n",
      "«                                                                            \n",
      "«cr_1: ══════════════════════════════════════════════════════════════════════\n",
      "«                                                                            \n",
      "«cr_2: ══════════════════════════════════════════════════════════════════════\n",
      "«                                                                            \n"
     ]
    }
   ],
   "source": [
    "print(qv_circs_nomeas[0][0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Simulate the ideal QV circuits\n",
    "\n",
    "The quantum volume method requires that we know the ideal output for each circuit, so we use the statevector simulator in Aer to get the ideal result."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Simulating trial 0\n",
      "Simulating trial 1\n",
      "Simulating trial 2\n",
      "Simulating trial 3\n",
      "Simulating trial 4\n",
      "Simulating trial 5\n",
      "Simulating trial 6\n",
      "Simulating trial 7\n",
      "Simulating trial 8\n",
      "Simulating trial 9\n",
      "Simulating trial 10\n",
      "Simulating trial 11\n",
      "Simulating trial 12\n",
      "Simulating trial 13\n",
      "Simulating trial 14\n",
      "Simulating trial 15\n",
      "Simulating trial 16\n",
      "Simulating trial 17\n",
      "Simulating trial 18\n",
      "Simulating trial 19\n",
      "Simulating trial 20\n",
      "Simulating trial 21\n",
      "Simulating trial 22\n",
      "Simulating trial 23\n",
      "Simulating trial 24\n",
      "Simulating trial 25\n",
      "Simulating trial 26\n",
      "Simulating trial 27\n",
      "Simulating trial 28\n",
      "Simulating trial 29\n",
      "Simulating trial 30\n",
      "Simulating trial 31\n",
      "Simulating trial 32\n",
      "Simulating trial 33\n",
      "Simulating trial 34\n",
      "Simulating trial 35\n",
      "Simulating trial 36\n",
      "Simulating trial 37\n",
      "Simulating trial 38\n",
      "Simulating trial 39\n",
      "Simulating trial 40\n",
      "Simulating trial 41\n",
      "Simulating trial 42\n",
      "Simulating trial 43\n",
      "Simulating trial 44\n",
      "Simulating trial 45\n",
      "Simulating trial 46\n",
      "Simulating trial 47\n",
      "Simulating trial 48\n",
      "Simulating trial 49\n"
     ]
    }
   ],
   "source": [
    "#The Unitary is an identity (with a global phase)\n",
    "backend = qiskit.Aer.get_backend('statevector_simulator')\n",
    "ideal_results = []\n",
    "for trial in range(ntrials):\n",
    "    print('Simulating trial %d'%trial)\n",
    "    ideal_results.append(qiskit.execute(qv_circs_nomeas[trial], backend=backend).result())\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we load the ideal results into a quantum volume fitter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "qv_fitter = qv.QVFitter(qubit_lists=qubit_lists)\n",
    "qv_fitter.add_statevectors(ideal_results)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3: Calculate the heavy outputs\n",
    "\n",
    "To define when a model circuit $U$ has been successfully implemented in practice, we use the *heavy output* generation problem. The ideal output distribution is $p_U(x) = |\\langle x|U|0 \\rangle|^2$, \n",
    "where $x \\in \\{0,1\\}^m$ is an observable bit-string. \n",
    "\n",
    "Consider the set of output probabilities given by the range of $p_U(x)$ sorted in ascending order \n",
    "$p_0 \\leq p_1 \\leq \\dots \\leq p_{2^m-1}$. The median of the set of probabilities is \n",
    "$p_{med} = (p_{2^{m-1}} + p_{2^{m-1}-1})/2$, and the *heavy outputs* are\n",
    "$$ H_U = \\{ x \\in \\{0,1\\}^m \\text{ such that } p_U(x)>p_{med} \\}.$$\n",
    "The heavy output generation problem is to produce a set of output strings such that more than two-thirds are heavy.\n",
    "\n",
    "As an illustration, we print the heavy outputs from various depths and their probabilities (for trial 0):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "qv_depth_3_trial_0: ['000', '001', '100', '111']\n",
      "qv_depth_4_trial_0: ['0000', '0100', '0101', '1000', '1001', '1011', '1100', '1101']\n",
      "qv_depth_5_trial_0: ['00000', '00011', '00100', '00101', '00111', '01001', '01011', '01100', '10000', '10011', '10101', '10110', '11000', '11001', '11010', '11101']\n",
      "qv_depth_6_trial_0: ['000011', '000110', '000111', '001000', '001100', '001110', '001111', '010001', '010011', '010101', '011000', '011100', '011101', '100001', '100101', '100110', '100111', '101000', '101001', '101011', '101100', '101101', '101110', '101111', '110011', '110100', '110101', '110110', '111001', '111010', '111011', '111110']\n"
     ]
    }
   ],
   "source": [
    "for qubit_list in qubit_lists:\n",
    "    l = len(qubit_list)\n",
    "    print ('qv_depth_'+str(l)+'_trial_0:', qv_fitter._heavy_outputs['qv_depth_'+str(l)+'_trial_0'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "qv_depth_3_trial_0: 0.8364265965659454\n",
      "qv_depth_4_trial_0: 0.8954287202366203\n",
      "qv_depth_5_trial_0: 0.8721440467960914\n",
      "qv_depth_6_trial_0: 0.8499058961161158\n"
     ]
    }
   ],
   "source": [
    "for qubit_list in qubit_lists:\n",
    "    l = len(qubit_list)\n",
    "    print ('qv_depth_'+str(l)+'_trial_0:', qv_fitter._heavy_output_prob_ideal['qv_depth_'+str(l)+'_trial_0'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Define the noise model\n",
    "\n",
    "We define a noise model for the simulator. To simulate decay, we add depolarizing error probabilities to the CNOT and U gates."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "noise_model = NoiseModel()\n",
    "p1Q = 0.002\n",
    "p2Q = 0.02\n",
    "noise_model.add_all_qubit_quantum_error(depolarizing_error(p1Q, 1), 'u2')\n",
    "noise_model.add_all_qubit_quantum_error(depolarizing_error(2*p1Q, 1), 'u3')\n",
    "noise_model.add_all_qubit_quantum_error(depolarizing_error(p2Q, 2), 'cx')\n",
    "#noise_model = None"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can execute the QV sequences either using Qiskit Aer Simulator (with some noise model) or using IBMQ provider, and obtain a list of exp_results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Running trial 0\n",
      "Running trial 1\n",
      "Running trial 2\n",
      "Running trial 3\n",
      "Running trial 4\n",
      "Running trial 5\n",
      "Running trial 6\n",
      "Running trial 7\n",
      "Running trial 8\n",
      "Running trial 9\n",
      "Running trial 10\n",
      "Running trial 11\n",
      "Running trial 12\n",
      "Running trial 13\n",
      "Running trial 14\n",
      "Running trial 15\n",
      "Running trial 16\n",
      "Running trial 17\n",
      "Running trial 18\n",
      "Running trial 19\n",
      "Running trial 20\n",
      "Running trial 21\n",
      "Running trial 22\n",
      "Running trial 23\n",
      "Running trial 24\n",
      "Running trial 25\n",
      "Running trial 26\n",
      "Running trial 27\n",
      "Running trial 28\n",
      "Running trial 29\n",
      "Running trial 30\n",
      "Running trial 31\n",
      "Running trial 32\n",
      "Running trial 33\n",
      "Running trial 34\n",
      "Running trial 35\n",
      "Running trial 36\n",
      "Running trial 37\n",
      "Running trial 38\n",
      "Running trial 39\n",
      "Running trial 40\n",
      "Running trial 41\n",
      "Running trial 42\n",
      "Running trial 43\n",
      "Running trial 44\n",
      "Running trial 45\n",
      "Running trial 46\n",
      "Running trial 47\n",
      "Running trial 48\n",
      "Running trial 49\n"
     ]
    }
   ],
   "source": [
    "backend = qiskit.Aer.get_backend('qasm_simulator')\n",
    "basis_gates = ['u1','u2','u3','cx'] # use U,CX for now\n",
    "shots = 1024\n",
    "exp_results = []\n",
    "for trial in range(ntrials):\n",
    "    print('Running trial %d'%trial)\n",
    "    exp_results.append(qiskit.execute(qv_circs[trial], basis_gates=basis_gates, backend=backend, noise_model=noise_model, backend_options={'max_parallel_experiments': 0}).result())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5: Calculate the average gate fidelity\n",
    "\n",
    "The *average gate fidelity* between the $m$-qubit ideal unitaries $U$ and the executed $U'$ is:\n",
    "$$ F_{avg}(U,U') = \\frac{|Tr(U^{\\dagger}U')|^2/2^m+1}{2^m+1}$$\n",
    "\n",
    "The observed distribution for an implementation $U'$ of model circuit $U$ is $q_U(x)$, and the probability of sampling\n",
    "a heavy output is:\n",
    "$$ h_U = \\sum_{x \\in H_U} q_U(x)$$\n",
    "\n",
    "As an illustration, we print the heavy output counts from various depths (for trial 0):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "qv_depth_3_trial_0: 792\n",
      "qv_depth_4_trial_0: 788\n",
      "qv_depth_5_trial_0: 736\n",
      "qv_depth_6_trial_0: 651\n"
     ]
    }
   ],
   "source": [
    "qv_fitter.add_data(exp_results)\n",
    "for qubit_list in qubit_lists:\n",
    "    l = len(qubit_list)\n",
    "    #print (qv_fitter._heavy_output_counts)\n",
    "    print ('qv_depth_'+str(l)+'_trial_0:', qv_fitter._heavy_output_counts['qv_depth_'+str(l)+'_trial_0'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 6: Calculate the achievable depth\n",
    "\n",
    "The probability of observing a heavy output by implementing a randomly selected depth $d$ model circuit is:\n",
    "$$h_d = \\int_U h_U dU$$\n",
    "\n",
    "The *achievable depth* $d(m)$ is the largest $d$ such that we are confident that $h_d > 2/3$. In other words,\n",
    "$$ h_1,h_2,\\dots,h_{d(m)}>2/3 \\text{ and } h_{d(m+1)} \\leq 2/3$$\n",
    "\n",
    "We now convert the heavy outputs in the different trials and calculate the mean $h_d$ and the error for plotting the graph."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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tsPJipUrV9K8efNq78fdWbp0KQsXLqRLly5piKzq1PUsIiIi1bZ27VratGmz1SaJ6WRmtGnTpla0zipRFBERkbRQkpg+teW1VKIoIiIiIgkpURQREZE6b+nSpeTn55Ofn0+HDh3Ycccdyc/Pp2XLlnTv3j3txyssLGTAgAGV2qagoCDhTT7GjRvHhRdemK7Q0kqJooiIiNR5bdq0YcaMGcyYMYPzzjuPSy65ZOPzBg0qTnc2bNhQA1HWPUoURUREpF4rKSnh3HPPpUePHhx55JGsWbMGCC18w4YNo3fv3txxxx0sWbKEk046iT59+tCnTx/effddAN56662NrZW9evVi5cqVABQVFfHLX/6S3XffnVNOOQV3B+CNN96gV69e9OzZk7POOot169ZtEdMjjzxC165d2W+//TYepzZSoigiIiJpZ2ZJlwcffHBjvQcffLDcuukwZ84cLrjgAj777DNatmzJs88+u3Hd+vXrmTZtGpdeeikXX3wxl1xyCf/+97959tlnOeeccwAYPXo099xzDzNmzODtt9+madOmAHz44YeMGTOGmTNnMnfuXD744APWrl3L4MGDGT9+PJ988gkbNmzgvvvu2yyeRYsWce211/Luu+/yzjvvMHPmzLScZyYoURQREZF6rUuXLuTn5wOw7777Mn/+/I3rBg4cuPHniRMncuGFF5Kfn8+xxx7LihUrKCoq4sADD2T48OHceeedLF++nIYNwzTU++23Hx07dqRBgwbk5+ezYMECZs+eTZcuXejatSsAZ5xxBpMnT94snilTplBQUEC7du1o3LjxZjHUNppwW0REar2CAli+PJ8ZM7IdiaSqrBu2IkOGDGHIkCEZjaVJkyYbf87JydnY9QzQrFmzjT+XlpbywQcfkJubu9n2V155JUcffTSvvPIKBx54IBMmTEi435KSkkydQtaoRVFEREQEOPLII7nrrrs2Pp8R/Wfy5Zdf0rNnT6644gr69OnD559/nnQf3bp1Y/78+XzxxRcAPPbYYxxyyCGb1enbty9vvfUWS5cupbi4mKeffjoDZ5MeWUkUzex8M5tnZmvNbLqZ/ayC+heY2SwzW2Nms83s9AR1TjKzmWa2Lno8IXNnICIiIvXNnXfeybRp09hrr73o3r07999/PwBjxoxhzz33ZK+99qJRo0b0799/i22XLYOlSxuRm5vLI488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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x7f9c3134bc50>"
      ]
     },
     "metadata": {
      "needs_background": "light"
     },
     "output_type": "display_data"
    }
   ],
   "source": [
    "plt.figure(figsize=(10, 6))\n",
    "ax = plt.gca()\n",
    "\n",
    "# Plot the essence by calling plot_rb_data\n",
    "qv_fitter.plot_qv_data(ax=ax, show_plt=False)\n",
    "\n",
    "# Add title and label\n",
    "ax.set_title('Quantum Volume for up to %d Qubits \\n and %d Trials'%(len(qubit_lists[-1]), ntrials), fontsize=18)\n",
    "\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 7: Calculate the Quantum Volume\n",
    "\n",
    "\n",
    "The quantum volume treats the width and depth of a model circuit with equal importance and measures the largest squareshaped (i.e., $m = d$) model circuit a quantum computer can implement successfully on average. \n",
    "\n",
    "The *quantum volume* $V_Q$ is defined as\n",
    "$$\\log_2 V_Q = \\arg\\max_{m} \\min (m, d(m))$$"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We list the statistics for each depth. For each depth we list if the depth was successful or not and with what confidence interval. For a depth to be sucessful the confidence interval must be > 97.5%."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Width/depth 3 greater than 2/3 (0.796309) with confidence 0.988582 (successful). Quantum volume 8\n",
      "Width/depth 4 greater than 2/3 (0.702207) with confidence 0.708690 (unsuccessful).\n",
      "Width/depth 5 greater than 2/3 (0.703359) with confidence 0.714988 (unsuccessful).\n",
      "Width/depth 6 less than 2/3 (unsuccessful).\n"
     ]
    }
   ],
   "source": [
    "qv_success_list = qv_fitter.qv_success()\n",
    "qv_list = qv_fitter.ydata\n",
    "QV = 1\n",
    "for qidx, qubit_list in enumerate(qubit_lists):\n",
    "    if qv_list[0][qidx]>2/3:\n",
    "        if qv_success_list[qidx][0]:\n",
    "            print(\"Width/depth %d greater than 2/3 (%f) with confidence %f (successful). Quantum volume %d\"%\n",
    "                  (len(qubit_list),qv_list[0][qidx],qv_success_list[qidx][1],qv_fitter.quantum_volume()[qidx]))\n",
    "            QV = qv_fitter.quantum_volume()[qidx]\n",
    "        else:\n",
    "            print(\"Width/depth %d greater than 2/3 (%f) with confidence %f (unsuccessful).\"%\n",
    "                  (len(qubit_list),qv_list[0][qidx],qv_success_list[qidx][1]))\n",
    "    else:\n",
    "        print(\"Width/depth %d less than 2/3 (unsuccessful).\"%len(qubit_list))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The Quantum Volume is: 8\n"
     ]
    }
   ],
   "source": [
    "print (\"The Quantum Volume is:\", QV)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:YaelEnv]",
   "language": "python",
   "name": "conda-env-YaelEnv-py"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
